Cloudfront 502 Bad gateway 에러 처리하기

도메인 접속 시 502 Bad Gateway 에러가 난다면 당황스럽기 마련입니다.
저도 최근 SST(Serverless Stack) + Next.js를 활용한 프로젝트를 배포하면서 같은 문제를 겪었고, 꽤나 삽질 끝에 원인을 찾고 해결했습니다.

이 글에서는 CloudFront 502 에러의 실제 원인과 해결 과정을 정리해 보겠습니다.

문제 상황 요약

• SST를 이용해 Next.js 앱을 AWS에 서버리스 방식으로 배포
• CloudFront를 통해 도메인 연결도 완료
• 그런데 어느 순간부터 CloudFront에서 502 Bad Gateway 에러 발생
• 이전 브랜치로 돌려도 증상은 동일

CloudFront → Lambda → 실패 → 502 응답

초기 접근과 삽질

처음에는 단순히 캐시 문제이거나, 도메인 설정 이슈라고 생각했습니다. CloudFront 함수나 도메인 설정, DNS 등을 다 점검해봤지만 문제가 해결되지 않았습니다.
이것저것 디버깅 중에 CloudWatch 로그를 확인해봤고 뭔가 꽂히는 에러를 마주했습니다.(sst는 로깅까지도 구축을 도와줘서 너무 편함!)

Error: canvas.node: invalid ELF header

원인 분석: Lambda와 native 모듈

Next.js에서 이미지 관련 기능이나 그래픽 처리 라이브러리(konva, canvas, sharp 등)를 사용하는 경우, 이것들이 내부적으로 native 바이너리(node-gyp 빌드된 .node 파일) 를 포함하고 있을 수 있습니다.
이런 모듈은 로컬(Mac 등)에서는 잘 작동하지만, AWS Lambda는 Amazon Linux 환경이기 때문에 서로 호환되지 않아 오류가 발생한다고 합니다!

제 경우는 konva를 사용했는데, 이 라이브러리가 내부적으로 canvas 모듈을 의존하고 있었습니다.
canvas.node가 Lambda에 포함되었고, 실행 중 로딩에 실패 → Lambda crash → CloudFront 502.

해결 방법

✅ 1. konva를 클라이언트 전용으로 분리

Next.js는 서버와 클라이언트가 같은 코드에서 동작하기 때문에, konva를 서버(Lambda)에서 실행하지 않도록 아래처럼 처리했습니다.

✔ 클라이언트 전용 컴포넌트로 분리

'use client';

import { Stage, Layer, Rect } from 'react-konva';

export default function KonvaCanvas() {
  return (
    <Stage width={500} height={500}>
      <Layer>
        <Rect x={10} y={10} width={100} height={100} fill="red" />
      </Layer>
    </Stage>
  );
}

✔ SSR에서 동적 import

import dynamic from 'next/dynamic';

const KonvaCanvas = dynamic(() => import('./KonvaCanvas'), {
  ssr: false,
});

export default function Page() {
  return <KonvaCanvas />;
}

마무리

CloudFront의 502 Bad Gateway는 생각보다 다양하고 복잡한 원인이 있습니다.
이번 사례처럼 Lambda 내부에서 native 모듈이 실행되지 못해 실패하는 경우도 많습니다.
저도 모듈 관련한 이슈를 가끔 마주하는데 로깅을 통한 디버깅 경험을 쌓을 수 있어 기분이 좋습니다.(약 2시간을 버린듯 하지만)

정리하자면

• CloudFront 502는 Lambda 실패일 가능성이 높다
• 로그 확인은 CloudWatch에서
• native 모듈은 Lambda에서 작동하지 않을 수 있음
• 그래픽/이미지 관련 처리는 클라이언트 전용 컴포넌트로 격리

이 글이 비슷한 상황에 처한 분들에게 도움이 되길 바랍니다.